Skip to content

fix(kitchen-sink): hired seats answer the admin credential that hired them (FIX-1548) - #2148

Merged
jhoffner merged 6 commits into
mainfrom
fix/fix-1548
Sep 24, 2026
Merged

jhoffner merged 6 commits into
mainfrom
fix/fix-1548

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

In the kitchen-sink, an operator who hires a seat at runtime (through workforce-admin's hire, with their admin token) can't use it. Opening a session with the seat, or sending it an action, comes back 404 Unknown flow even with the same token that hired it. The seat is pinned to the operator's organization, but it heard every request as the framework's default organization, so its own pin turned the operator away. The reference app's runtime-hire story stopped at "hired" and never reached "used".

What this does

Every seat the app admits from a roster row now resolves its callers with the same admin credential the workforce-admin flow uses. A request carrying the hiring token resolves to the hiring organization and user, which is exactly what the seat is pinned to, so it's served. The pin itself is unchanged. Another organization's token still gets the 404 an unknown address gets, and a request with no token now gets 401. It was refused before too.

This applies to seats hired by the admin action, seats brought back by the boot reload, and seats hired by another seat's hire tool. All three go through the same door. The app's open flows and the file-declared seats are untouched.

What's asked of you

Nothing here is yours to decide. This is a bug fix and this PR is where it gets reviewed.

Parts worth reviewing closely

  • apps/kitchen-sink/lib/workforce-registrar.ts → registerFromRoster: the one-line change that wraps each admitted seat. Check it is the only admission path for pinned seats. hire, the boot reload in fsdev.config.ts, and kitchenSinkSeatHireOptions.register all go through it.
  • apps/kitchen-sink/lib/workforce-admin-auth.ts → withAdminAuthentication: it copies the FlowInstance with an authentication.resolvePrincipal added. Instances are plain objects (core's createFlowInstance returns a literal), but review whether anything downstream depends on the object the hire minted being the same one the registry holds. Nothing I found does: fire and kindAt go by address.
  • BP-031: the seat's identity comes only from the verified bearer token. The test's refusal cases put the right userId and orgId in the body and are still refused.

Links: Linear FIX-1548 · follow-on to FIX-1529 (#2091, the pin this respects) · framework follow-up FIX-1552 · Bug route, no spec · merges after review.

How to review this
PR kind The one question The human judges Automated review helps most on Do not report
Implementation PR (fix/<ISSUE-ID>, merges) Is this correct, and does it match the approved direction? The implementation decisions and their ramifications, what was subtracted, whether the goal was actually proved Correctness, second paths (BP-035), auth/routing from caller-controllable input (BP-031), legacy-shape tolerance (BP-030), concurrency and null boundaries Re-litigating a Decision the spec already settled and a human approved; style the codebase has already settled
Engineering calls
  • Per-instance resolver, not a host-level one. A resolvePrincipal on createFlowState would govern every flow that has no resolver of its own. In this app that includes chat-agent, rich-text-component, the channels and the file-declared seats, all of which the browser reaches as devuser with no token. Putting the admin token in front of them would break the demo. A host resolver that falls back to the default for tokenless callers doesn't work either (next point). A resolver on the kind has the same problem for the file-declared seats of that kind. The seat instance is the one place that covers exactly the pinned seats. It uses core's existing instance-level authentication override, so there is no new mechanism.
  • Host-level alternative checked and refused. Review suggested a composite host resolver (bearer token → admin principal, no token → delegate to defaultBodyUserIdPrincipalResolver). A probe on createFlowState with chat-agent showed it breaks every tokenless open flow, because the engine recognises the development default by the resolver's brand (isDefaultBodyUserIdPrincipalResolver), and a wrapper that delegates to the default carries no brand:
    • Actions: host.resolve treats the composite as a configured resolver, finds no verified org, and answers 401 "Request requires a verified organization".
    • Management routes: route-auth turns enforcement on, calls the resolver with no body, the default branch returns null, and requireUser answers 401. Creating a chat-agent session as devuser goes from 201 to 401.
    • Listings: GET /sessions goes from 200 to 401 by the same path, which is the disabled-composer failure management-routes-reachable.test.ts guards.
  • Architecture doc now matches. docs/architecture/authentication.md (route-auth section) said to install the hire flow's resolver at the host. It now says: at the host when every flow authenticates, or on the seat instance in a mixed app. It also says why a delegating host resolver fails, and that the seat then stays out of the catalog and host listings.
  • In the registrar door, not at each call site. The alternative was wrapping the kinds map passed to hireWorkforce and reloadHiredSeats, so the resolver goes in at mint time through the factory's instance options. That needs a wrapped callable that copies the kind's blueprint metadata, in two places, and it misses the seat-tool path. The door already exists because all three paths have to agree (it holds the provenance mark fire relies on).
  • The resolver is read once, at module scope, as the admin flow's is. Both read the same env at the same point in the boot, so a seat resolves a caller exactly as the hire that pinned it did. With no credential configured it is undefined and the seat is left alone. The pin then refuses everyone, so it fails closed.
  • A kind that names its own resolver keeps it. No kitchen-sink kind does today. Silently overriding one would be the wrong default if one ever does.
  • Why this is reusable outside the kitchen-sink: the pattern is "the door that registers a pinned seat installs the resolver that produced the pin", on public API (FlowInstance.authentication, registerHiredSeat). A Lab or another host does the same in its own registerSeat. A first-class authentication option on hireWorkforce/reloadHiredSeats would be the framework-level version. That is out of scope here (kitchen-sink wiring only), and noted below.
Everything else

Verification (all with FSDEV_DEFAULT_MODEL and FSDEV_INTENT_* unset)

New test apps/kitchen-sink/test/hired-seat-auth.test.ts drives the real router from createFlowState. It installs the registrar over the FlowState's own door as fsdev.config.ts does, hires support.bo (a desk-clerk) over HTTP with acme's admin bearer token, then:

Case Before (main) After
open a session on the seat, acme token 404 Unknown flow 201
run answer on the seat, acme token 404 Unknown flow 202 → completed
restart on the same stores, boot reload, run answer, acme token 404 Unknown flow 202 → completed
open / run, bravo's admin token 404 404 (unchanged)
open / run, no token, body naming the admin user and acme refused 401 (asserted exactly)
  • Red → green: on unmodified main the three positive cases fail with 404 Unknown flow "acme.~workforce-admin.support.bo" and the two refusal cases pass.
  • Fence-break: with only the withAdminAuthentication(...) call in registerFromRoster reverted to impl.register(seat, { pin }), exactly the three positive cases go red (3 failed / 2 passed). Restored, 5/5 pass.
  • apps/kitchen-sink suite: 20 files, 147 tests passing (including the existing workforce-admin and manager-seat suites, which exercise the same registrar).
  • pnpm turbo run typecheck --filter=@flow-state-dev/kitchen-sink: passes.

Second paths (BP-035)

  • No credential configured: the admin flow isn't registered and the resolver is undefined, so seats are left as they were. A reloaded seat whose org has no admin token is still pinned and still refuses. Fail-closed, as before.
  • Seat-tool hires: these now get the same resolver. In this app a seat can only hire under a real org when it was itself reached under one, and after this change that happens only through the admin token, so the seats it hires are pinned to the same principal and answer the same token. Pins naming another user (e.g. manager-seat.test.ts's desk-lead) are still refused for the admin token by the pin's user half.
  • Anonymous cross-flow listings: hired seats now count as authenticated flows, so their sessions are withheld from anonymous GET /sessions listings. That's tighter than before, not looser.

Left alone: framework follow-up FIX-1552

  • The catalog and host listings still hide the seat from the operator. GET /api/flows with the acme token lists workforce-admin but not the hired seat; a throwaway probe confirmed it. The catalog (flowsForCaller in packages/engine/src/routes/http-handlers.ts) and the host listings resolve the caller with the host resolver only, which is the default here. FIX-1552 is the framework follow-up: either the catalog and listings honour per-instance resolvers, or the engine offers a supported fallback combinator for host resolvers so a mixed app can set one without breaking its open flows. Opening and running the seat, which is what this bug is about, work now.
  • Framework seam: hireWorkforce / reloadHiredSeats take no authentication option, so a host can't set a seat's resolver at mint time without wrapping kinds. Not needed for this fix.

Docs changed

  • docs/architecture/authentication.md: one sentence in the route-auth section, as above.
  • apps/docs/docs/workforce/durable-hire.md: install the hiring resolver on the hired seat (registerSeat) rather than host-wide. The page says who the seat then answers, and the calling example sends the admin token. Awaiting a docs-editor pass.
  • apps/kitchen-sink/README.md: a curl showing the hired seat answering the hiring token, the refusals, and the user-owned address form (acme.~workforce-admin.support.bo).

Changeset: none. The kitchen-sink is private and no published package changed (BP-022).

Files

  • apps/kitchen-sink/lib/workforce-admin-auth.ts: withAdminAuthentication(seat, resolver)
  • apps/kitchen-sink/lib/workforce-registrar.ts: module-scope hiredSeatResolver; registerFromRoster wraps the seat
  • apps/kitchen-sink/test/hired-seat-auth.test.ts: new, HTTP-level
  • apps/kitchen-sink/README.md: runtime-hire section
  • apps/docs/docs/workforce/durable-hire.md: resolver on the seat
  • docs/architecture/authentication.md: where a hired seat's resolver goes

🤖 Generated with Claude Code

https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D

… them (FIX-1548)

A seat hired over workforce-admin is pinned to the org and user the admin
token resolved, but the seat itself carried no resolver. Every request to it
fell to the framework default, which names the default org, so the pin
refused even the operator who had just hired it.

The roster door (workforceRegistrar.registerFromRoster) now installs the
admin flow's own resolver on each seat instance it admits, covering the
admin hire, the boot reload, and seat-tool hires. The pin and fences are
unchanged: another org's token is still refused (404), and no token gets 401.

Adds an HTTP-level regression test through createFlowState's router:
hire, then open/run the seat with the same token, including after a
restart reload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 24, 2026 7:04pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 24, 2026 7:04pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 24, 2026 7:04pm UTC

Request Review

@cursor

cursor Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e074fadf-9377-4927-a8fc-eca16d4c2ea6)

@linear-code

linear-code Bot commented Sep 24, 2026

Copy link
Copy Markdown

FIX-1548

…he host

A hired seat checks every request against the principal that hired it, and
that principal comes from the seat's own authentication or the host's. The
page told readers to put the resolver on the host, which applies it to every
flow the host serves. It now says to put it on the seat where the app
registers it, and the registerSeat example does so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
The durable-hire page now states the limit of putting the hiring resolver on
the seat, names the default-organization mismatch that produces the 404, and
stops promising every member access to an org-visible seat when the example
registers it with the admin resolver. The calling example sends the admin
token. The kitchen-sink README's address example names the seat its hire and
call examples use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
…1 (FIX-1548)

The README promises 401 with no token. Pin that instead of accepting
401 or 404.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-24T19:03:10.657470Z a082bb3 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a082bb3958

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@jhoffner
jhoffner marked this pull request as draft September 24, 2026 18:58
@jhoffner
jhoffner marked this pull request as ready for review September 24, 2026 18:58
… app (FIX-1548)

The route-auth section told readers to install the hire flow's resolver at
the host. In a mixed app whose other flows stay on the development default
that breaks them: the engine recognises the development default by the
resolver that runs, so a host resolver delegating to the default refuses
tokenless callers on actions, management routes and listings. The section
now says to install it at the host when every flow authenticates, or on the
seat instance otherwise, and states the listing consequence of the latter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a082bb3958

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/kitchen-sink/README.md Resolved
…1548)

Every configured token for an organization resolves to the same admin
principal, so the pin cannot tell them apart. Say so rather than imply the
seat is bound to the hiring token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@jhoffner
jhoffner merged commit 55c9581 into main Sep 24, 2026
12 checks passed
@jhoffner
jhoffner deleted the fix/fix-1548 branch September 24, 2026 19:36
jhoffner pushed a commit that referenced this pull request Sep 24, 2026
Resolve the kitchen-sink README: keep PR-B's pinned-token paragraph and
fold in #2148's hired-seat paragraph re-keyed to kitchen-sink
(kitchen-sink.~workforce-admin.support.bo; no token gets 401; the
other-organization 404 no longer applies because such tokens are refused
at boot). Move #2148's hired-seat-auth.test.ts off acme/bravo to the
pinned organization; its other-org case becomes a token refused at boot,
answered 401 at the seat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants